@fp-ts/schema

Schema validation with static type inference

flowchart TD
  Schema -->|codecFor| Codec
  Schema -->|guardFor| Guard
  Schema -->|arbitraryFor| Arbitrary
  Schema -->|prettyFor| Pretty

Features

• deriving single artifacts from a Schema:
  • Codec
  • Guard
  • Arbitrary
  • Pretty
• Codec (all in one artifact)
• custom interpreters
• custom schema combinators
• custom data types
• custom decode errors
• versioning (TODO)
• migration (TODO)

Summary

import * as C from "@fp-ts/schema/Codec";

const Person = C.struct({
  name: C.string,
  age: C.number,
});

// extract the inferred type
type Person = C.Infer<typeof Person>;
/*
type Person = {
  readonly name: string;
  readonly age: number;
}
*/

import * as DE from "@fp-ts/schema/DecodeError";

// decode from JSON
expect(Person.decode({ name: "name", age: 18 })).toEqual(
  C.success({ name: "name", age: 18 })
);
expect(Person.decode(null)).toEqual(
  C.failure(DE.notType("{ readonly [_: string]: unknown }", null))
);

// encode to JSON
expect(Person.encode({ name: "name", age: 18 })).toEqual({
  name: "name",
  age: 18,
});

// guard
expect(Person.is({ name: "name", age: 18 })).toEqual(true);
expect(Person.is(null)).toEqual(false);

// pretty print
expect(Person.pretty({ name: "name", age: 18 })).toEqual(
  '{ "name": "name", "age": 18 }'
);

import * as fc from "fast-check";

// fast-check arbitrary
console.log(fc.sample(Person.arbitrary(fc), 2));
/*
[
  { name: '!U?z/X', age: -2.5223372357846707e-44 },
  { name: 'valukeypro', age: -1.401298464324817e-45 }
]
*/

Custom interpreters

src/Pretty.ts, src/Guard.ts and src/Arbitrary.ts are good examples of defining a custom interpreter.

Custom schema combinators

Examples in /src/Schema.ts.

All the combinators defined in /src/Schema.ts could be implemented in userland.

Custom data types

Examples in /src/data/*

Understanding Schemas

A schema is a description of a data structure that can be used to generate various artifacts from a single declaration.

Guard

A Guard is a derivable artifact that is able to refine a value of type unknown to a value of type A.

interface Guard<A> extends Schema<A> {
  readonly is: (input: unknown) => input is A;
}

Arbitrary

An Arbitrary is a derivable artifact that is able to produce fast-check arbitraries.

interface Arbitrary<in out A> extends Schema<A> {
  readonly arbitrary: (fc: typeof FastCheck) => FastCheck.Arbitrary<A>;
}

Pretty

A Pretty is a derivable artifact that is able to pretty print a value of type A.

interface Pretty<in out A> extends Schema<A> {
  readonly pretty: (a: A) => string;
}

Codec

A Codec is a derivable artifact that is able to:

• decode a value of type unknown to a value of type A.
• encode a value of type A to a value of type unknown.

interface Codec<in out A>
  extends Schema<A>,
    Decoder<unknown, A>,
    Encoder<unknown, A>,
    Guard<A>,
    Arbitrary<A>,
    Pretty<A> {}

Basic usage

Primitives

import * as C from "@fp-ts/schema/Codec";

// $ExpectType Codec<string>
C.string;

// $ExpectType Codec<number>
C.number;

// $ExpectType Codec<boolean>
C.boolean;

// $ExpectType Codec<bigint>
C.bigint;

// $ExpectType Codec<symbol>
C.symbol;

// $ExpectType Codec<unknown>
C.unknown;

// $ExpectType Codec<any>
C.any;

Filters

// $ExpectType Codec<string>
pipe(C.string, C.minLength(1));

// $ExpectType Codec<string>
pipe(C.string, C.maxLength(10));

// $ExpectType Codec<number>
pipe(C.number, C.lessThan(0));

// $ExpectType Codec<number>
pipe(C.number, C.lessThanOrEqualTo(0));

// $ExpectType Codec<number>
pipe(C.number, C.greaterThan(10));

// $ExpectType Codec<number>
pipe(C.number, C.greaterThanOrEqualTo(10));

// $ExpectType Codec<number>
pipe(C.number, C.int);

Literals

// $ExpectType Codec<"a">
C.literal("a");

// $ExpectType Codec<"a" | "b" | "c">
C.literal("a", "b", "c");

Native enums

enum Fruits {
  Apple,
  Banana,
}

// $ExpectType Codec<typeof Fruits>
C.nativeEnum(Fruits);

Unions

// $ExpectType Codec<string | number>
C.union(C.string, C.number);

Tuples

// $ExpectType Codec<readonly [string, number]>
C.tuple(C.string, C.number);

Rest element

// $ExpectType Schema<readonly [string, number, ...boolean[]]>
pipe(C.tuple(C.string, C.number), C.withRest(C.boolean));

Arrays

// $ExpectType Codec<readonly number[]>
C.array(C.number);

Non empty arrays

// $ExpectType Codec<readonly [number, ...number[]]>
C.nonEmptyArray(C.number);

Structs

// $ExpectType Codec<{ readonly a: string; readonly b: number; }>
C.struct({ a: C.string, b: C.number });

Optional fields

// $ExpectType Codec<{ readonly a: string; readonly b: number; readonly c?: boolean | undefined; }>
C.struct({ a: C.string, b: C.number }, { c: C.boolean });

Pick

// $ExpectType Codec<{ readonly a: string; }>
pipe(C.struct({ a: C.string, b: C.number }), C.pick("a"));

Omit

// $ExpectType Codec<{ readonly b: number; }>
pipe(C.struct({ a: C.string, b: C.number }), C.omit("a"));

Partial

// $ExpectType Codec<Partial<{ readonly a: string; readonly b: number; }>>
C.partial(C.struct({ a: C.string, b: C.number }));

String index signature

// $ExpectType Codec<{ readonly [_: string]: string; }>
C.stringIndexSignature(C.string);

Symbol index signature

// $ExpectType Codec<{ readonly [_: symbol]: string; }>
C.symbolIndexSignature(C.string);

Extend

// $ExpectType Codec<{ readonly a: string; readonly b: string; } & { readonly [_: string]: string; }>
pipe(
  C.struct({ a: C.string, b: C.string }),
  C.extend(C.stringIndexSignature(C.string))
);

Option

// $ExpectType Codec<Option<number>>
C.option(C.number);

ReadonlySet

// $ExpectType Codec<ReadonlySet<number>>
C.readonlySet(C.number);

Chunk

// $ExpectType Codec<Chunk<number>>
C.chunk(C.number);

List

// $ExpectType Codec<List<number>>
C.list(C.number);

Documentation

• API Reference

License

The MIT License (MIT)

Changelog

0.0.3

Patch Changes

• #127 fd87ac6 Thanks @mikearnaldi! - Fix release for github